home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / dirut / retain20.zip / RETAIN.DOC < prev    next >
Text File  |  1992-12-11  |  20KB  |  313 lines
  1. --- RETAIN 2.0 by Jim Groeneveld, 11/12-92, retains current path.
  2.     Pure BATch equivalent of PUSH/POPDIR, up to 7 levels, no TSR.
  3.     Multiple memory sets.Optionally shows all nested path levels.
  4.  
  5. ===Summary===
  6.  
  7. Vs. 2.0, BATch equiv. of PUSH/POPDIR, pure DOS, 7 levels, multiple sets, no TSR.
  8.  
  9. Version 2.0 optional advanced feature: user specification of RETURN.BAT file.
  10. I sacrified one directory level to remember for maintaining a variable memory
  11. file specification (RETURN). This file name and its location (previously fixed
  12. to C:\RETURN.BAT) can be specified as a command line parameter or an
  13. environment variable. It allows for maintaining multiple independent sets of
  14. directories to remember (theoretically an unlimited number). Good for multiple
  15. file systems (drives) and shells.
  16.  
  17. ===CONTENTS of package===
  18. This package (.ZIP) includes the following files:
  19. RETAIN   BAT      15,342  12-11-92  02:00:00  Original BATch program RETAIN
  20. RETAINCD BAT       1,673  12-11-92  02:00:00  Combination of RETAIN and CD
  21. $RETURN$ AUX          28  08-27-92  06:00:00  Auxiliary file (necessary)
  22. RETAIN   DOC      19,546  12-11-92  02:00:00  This documentation file
  23. PATH-BUG ZIP       1,923  11-20-89  11:38:38  2 messages about DOS PATH bug
  24.  
  25. ===USAGE: RETAIN current path===
  26. Enter 'RETAIN [aux-path[aux-file]│*│[/│-]?│+ [rtn-spec]]'
  27. from the directory to retain, in which:
  28. aux-path = drive:\subdir\ of auxiliary file $RETURN$.AUX, incl. trailing '\';
  29. aux-file = the eventual alternate auxiliary file name for $RETURN$.AUX;
  30. *        = list the currently stored paths (also with 'RETURN *');
  31. ? (or /? or -?) = display this help (also with 'RETURN [/│-]?');
  32. +        = dummy first argument if only second one specified;
  33. rtn-spec = (full drive, path and) file specification of the RETURN-file,
  34.            without '.BAT' extension, default C:\RETURN (new in version 2.0).
  35. DO NOT SPECIFY OTHER PARAMETERS. THIS WILL PRODUCE ERRONEOUS RESULTS!
  36. RETAIN may be called successive times to store up to 7 paths.
  37.  
  38. Instead of specifying the same names for the auxiliary path and the return file
  39. path (and name) each time these may be defined as environment variables. For
  40. the auxiliary path the variable name is RETAIN, for the return path (and file
  41. name) it is RETURN. For example (from the DOS prompt or AUTOEXEC.BAT):
  42. SET RETAIN=C:\UTIL\DATA\        (note trailing backslash)
  43. SET RETURN=C:\UTIL\      or   SET RETURN=C:\UTIL\GOBACK   (excl. '.BAT')
  44. Specified command line parameters will override these values.
  45.  
  46. ===USAGE: RETURN to previous path===
  47. Enter 'RETURN' (the literal command, not only the RETURN/ENTER-key) to return
  48. to the very last path stored in the path list (no parameters!). This path is
  49. removed from the list and RETAIN thus has one more level to store the next time.
  50. Enter 'RETURN *' to list the currently stored paths.
  51.  
  52. ===USAGE: RETAINCD to retain current path and change drive:subdirectory===
  53. Enter 'RETAINCD drive┼path [aux-path[aux-file]│*│[/│-]?│+ [rtn-spec]]',
  54. from the directory to retain, in which:
  55. drive    = drive specification to CD to, e.g. 'C:';
  56. path     = absolute (\[...[\...]]) or
  57.            relative   (...[\...]) path specification to CD to.
  58.     At least one of these (either drive or path) or both _must_ be specified.
  59. aux-path = drive:\subdir\ of auxiliary file $RETURN$.AUX, incl. trailing '\';
  60. aux-file = the eventual alternate auxiliary file name for $RETURN$.AUX;
  61. *        = list the currently stored paths;
  62. ? (or /? or -?) = display this help;
  63. +        = dummy second argument if additional third one specified;
  64. rtn-spec = (full drive, path and) file specification of the RETURN-file,
  65.            without '.BAT' extension, default C:\RETURN (new in version 2.0).
  66.  
  67. ***WARNING!!!***
  68. MANY (LONG) PATHS MAY CAUSE BAT FILE LINES TO EXCEED 127 CHARACTERS.
  69. THIS WILL CREATE UNPREDICTABLE, AND ERRONEOUS RESULTS!!!!!!!!!!!!!!!
  70. IN SOME INSTANCES THE SYSTEM MAY EVEN HANG OR CRASH! Thus, though the algorithm
  71. is correct the DOS command line length limitation may restrict its use.
  72.  
  73. ===Determination of location (and name) of auxiliary file $RETURN$.AUX===
  74. The auxiliary file $RETURN$.AUX will be searched for in the paths or as the
  75. full file specification (eventually with different, alternative filename and
  76. extension) from the data below in that order until it is found.
  77. a. the first and only parameter when calling RETAIN
  78.    1. the full _path_ only, incl. trailing '\' (e.g. 'RETAIN C:\UTIL\') or
  79.    2. the full _file_specification_ (e.g. 'RETAIN C:\UTIL\AUX-FILE.$$$')
  80. b. the environment variable %RETAIN% (specify environment variable RETAIN
  81.    either from the DOS prompt or in AUTOEXEC.BAT)
  82.    1. the full _path_ only, incl. trailing '\' (e.g. 'SET RETAIN=C:\UTIL\') or
  83.    2. the full _file_specification_ (e.g. 'SET RETAIN=C:\UTIL\AUX-FILE.$$$')
  84. c. the ROOT directory of C: (C:\) (or automatically any APPENDed path)
  85. d. the ROOT directory of the CURRENT drive (\)
  86. e. the CURRENT directory (.\)
  87. f. the PARENT directory of the current one (..\)
  88. g. the SAME directory where RETAIN.BAT is residing:
  89.    if EXPLICITELY specified when starting RETAIN (by path, DOS 3.x&up only)
  90.    (NOT if RETAIN.BAT can only be found via the PATH!) (e.g. 'C:\UTIL\RETAIN')
  91. h. the DOS PATH variable (this may take quite a while), new in version 1.1
  92.  
  93. So make sure to place or name $RETURN$.AUX such that it can be found in one of
  94. these ways. All this effort is done because the DOS ECHO command can not write
  95. lines without CRLF, so an external auxiliary file is necessary that already
  96. contains such a line.
  97.  
  98. ===Further remarks===
  99. If using DOS 3.2&up and using the APPEND path utility do at least specify the
  100. '/X' parameter when calling APPEND for the first time or the auxiliary file
  101. still can not be found.
  102.  
  103. It is handy to put RETAIN.BAT in a directory that is in your path (e.g.
  104. C:\UTIL) and to have C:\ in your path in order to be able to find the default
  105. temporary created file C:\RETURN.BAT from any drive:subdirectory or to take care
  106. to create the return file in a directory that is in your path.
  107.  
  108. In order to restart each time with an empty list when the system is booted
  109. add the following statement to your AUTOEXEC.BAT file (for each return file):
  110. IF EXIST c:\return.BAT DEL c:\return.BAT    (eventually redirect this to NUL)
  111.  
  112. ===Minimal system requirements===
  113. IBM-PC (88/86/x86) or compatible
  114. 64kb memory
  115. (MS)DOS 3.x or above; RETAIN vs. 1.1 still could be adapted easyly to work
  116. under DOS 2.x (no use of environment variables and no explicit path
  117. specifications before program calls), but this version relies highly upon the
  118. specification of paths when calling itself (or other batch files); in fact
  119. this is a main change. It can not be made suited for DOS 2.x because paths
  120. and file names for return files would have to be separated. Besides, who still
  121. is using DOS 2.x? (It could be made working under DOS 2.x, but that would need
  122. a complete revision and revised syntax and its possibilities, the number of
  123. paths stored, would decrease.) So from version 2.0 on only DOS 3.x and above
  124. is required. If one has hardware that does not allow for these DOS versions
  125. then one should use and adapt version 1.1 instead.
  126.  
  127. ===New in version 2.0===
  128. The name of RETAIN already might be changed with previous versions, though it
  129. was not yet documented, as long as DOS would be able to find it. RETAIN (or
  130. whatever it is called) knows its name (how it was called when started: %0) and
  131. uses that knowledge to call itself directly and indirectly (from RETURN) some
  132. times during its run. When it builds C:\RETURN.BAT (the return file) for the
  133. first time it also stores its own calling name in it in order to be called from
  134. there.
  135.  
  136. Up to vs. 2.0 the name and location of C:\RETURN.BAT was fixed within
  137. RETAIN.BAT. The user might patch that if it did not apply (e.g. if there is
  138. no C: drive). Now the name and location can be controlled from outside,
  139. without changing RETAIN.BAT, via a second argument or an environment variable
  140. RETURN. Without the use of user specified environment variables, introduced
  141. with DOS 3.0 (?), RETAIN is compatible with all version